<!DOCTYPE HTML><html lang="en">
<HEAD>

<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

<META charset="utf-8">

<LINK REL="STYLESHEET" HREF="../book.css" TYPE="text/css">
<TITLE>
Undo and the IDE Workbench
</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY>
<h3>Undo and the IDE Workbench</h3>
<p>
We've seen code snippets that use workbench protocol for accessing the operations history and the workbench undo
context.  This is achieved using <a href="../reference/api/org/eclipse/ui/operations/IWorkbenchOperationSupport.html"><b>IWorkbenchOperationSupport</b></a>,
which can be obtained from the workbench.  The notion of a workbench-wide undo context is fairly general.  It is up to the workbench application
to determine what specific scope is implied by the workbench undo context, and which views or editors use the
workbench context when providing undo support.
</p>
<p>
In the case of the Eclipse IDE workbench, the workbench undo context should be assigned to any operation that affects the IDE workspace at large.
This context is used by views that manipulate the workspace, such as the Resource Navigator.  The IDE workbench installs an adapter on
the workspace for <a href="../reference/api/org/eclipse/core/commands/operations/IUndoContext.html"><b>IUndoContext</b></a> that returns the
workbench undo context.  This model-based registration allows plug-ins that manipulate the workspace to obtain the appropriate undo context, even if they are headless and
do not reference any workbench classes.</p>
<pre>// get the operation history
IOperationHistory history = OperationHistoryFactory.getOperationHistory();

// obtain the appropriate undo context for my model
IUndoContext workspaceContext = (IUndoContext)ResourcesPlugin.getWorkspace().getAdapter(IUndoContext.class);
if (workspaceContext != null) {
	// create an operation and assign it the context
}

</pre>
Other plug-ins are encouraged to use this same technique for registering
model-based undo contexts.
<h3>Undoable Workspace Operations</h3>
<p>
Undoable operations are provided by the IDE plug-in that allow you to execute, 
undo, and redo common workspace manipulations.  Operations are provided for
creating, moving, copying, and deleting projects, folders, and files.  The IDE
plug-in uses these operations to provide undo support in the Resource Navigator.
These classes can also be used by clients.  They are available in the package
<a href="../reference/api/org/eclipse/ui/ide/undo/package-summary.html"><b>org.eclipse.ui.ide.undo</b></a>.
 </p>
<p>
Using the workspace undoable operations is similar to the examples shown for using
any <a href="../reference/api/org/eclipse/core/commands/operations/IUndoableOperation.html"><b>IUndoableOperation</b></a>.
The primary difference is that some of the details, such as assigning the appropriate
undo context, are handled internally by the operation.  The following snippet shows
how to use an undoable operation for creating a new file.
</p>
<pre>
IFile newFileHandle = IDEWorkbenchPlugin.getPluginWorkspace().getRoot().
	getFile(myNewFilePath);
CreateFileOperation op = new CreateFileOperation(newFileHandle, null,
	initialContentStream, "Create New File");
</pre>
<p>
The operation is configured with a file handle for the file to be created, an
input stream with the initial contents, and a label describing the operation.  Internally,
the operation will assign the workspace undo context and handle other details such
as keeping track of which resources the operation manipulates.  To execute the operation,
the caller uses the standard <a href="../reference/api/org/eclipse/core/commands/operations/IOperationHistory.html"><b>IOperationHistory</b></a>
protocol.  
</p>
<pre>
try {
	PlatformUI.getWorkbench().getOperationSupport().getOperationHistory()
		.execute(op, myProgressMonitor, 
			WorkspaceUndoUtil.getUIInfoAdapter(getShell()));
} catch (final ExecutionException e) {
	// handle exceptions
}
</pre>
<p>
Note that the caller is responsible for providing a progress monitor if desired, and
an <a href="../reference/api/org/eclipse/core/runtime/IAdaptable.html"><b>IAdaptable</b></a> that
can provide the shell that should be used for any prompting. The utility class
<a href="../reference/api/org/eclipse/ui/ide/undo/WorkspaceUndoUtil.html"><b>WorkspaceUndoUtil</b></a>
provides a utility method for creating the necessary adapter from a shell.  
</p>
<p>Callers are also responsible for determining whether to execute the operation in 
the UI thread, the background, or a workbench job.  If the operation should be executed 
in the background, then the caller should create the appropriate progress monitor and run the 
snippet shown above in the appropriate runnable.  
</p>
<p>The undo and redo of the operation will be performed by the undo and redo action handlers
when the user initiates undo or redo.  The standard workbench action handlers use 
<a href="../reference/api/org/eclipse/core/commands/operations/IAdvancedUndoableOperation2.html"><b>IAdvancedUndoableOperation2</b></a>
protocol to determine how to perform the undo and redo of operations.
All of the workspace operations implement protocol that instructs clients to run the undo or redo 
of the operation in the background if possible.
</p>
</BODY>
</HTML>
